Origin Configuration

(MI.SourceMetadataExtended)

Overview

The CDN acquires content from the origins. Each site host must define an origin.

The origin can be configured at the site level and inherited by hosts, and/or configured at the host level.

When both the site and host configuration define an origin, the host configuration overrides the site-level configuration.

A path may define an alternative origin. Otherwise it inherits the host origin.

An origin configuration may include a single origin host, or multiple origin hosts to support a failover or load-balancing workflow.

Media Delivery supports three origin types:

Single Origin: Uses a single origin to acquire content.
Origin with Failover: Configures a failover workflow with multiple origin hosts using timeouts and HTTP error codes.
Round Robin List: Configures load-balancing using a round robin method.

Basic Examples

Single Origin

In this simple example of a single origin configuration, the MI.SourceMetadataExtended object is explicitly configured for the www.mysite.com host.

{
  "hosts": [
    {
      "host": "www.mysite.com",
      "host-metadata": {
        "metadata": [
          {
            "generic-metadata-type": "MI.SourceMetadataExtended",
            "generic-metadata-value": {
              "sources": [
                {
                  "protocol": "https/1.1",
                  "endpoints": [
                    "www.exampleOrigin.com"
                  ]
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

Single Origin with Connection Control Rules

This example adds the connection-control attributes to set the maximum allowed time for connection with the origin server, the maximum allowed time for content acquisition from the origin, and the maximum allowed number of retries.

{
  "generic-metadata-type": "MI.SourceMetadataExtended",
  "generic-metadata-value": {
    "sources": [
      {
        "protocol": "https/1.1",
        "endpoints": [
          "www.exampleOrigin.com"
        ],
        "connection-control": {
          "connection-setup-timeout-ms": 5000,
          "byte-read-timeout-ms": 10000,
          "max-connection-retries-per-source": 2
        }
      }
    ]
  }
}

Origin with Failover

This is an example of a failover origin configuration, that specifies the failover conditions (failover-errors) and the failover host within the sources array. A request is redirected to the failover origin if a response is not returned by the primary origin host within 1200 milliseconds, or if any of the specified errors occur.

{
  "generic-metadata-type": "MI.SourceMetadataExtended",
  "generic-metadata-value": {
    "sources": [
      {
        "protocol": "https/1.1",
        "endpoints": [
          "primary-origin.example.com"
        ],
        "origin-host": "content.example.com", //Override Host Header
        "connection-control": {
          "connection-setup-timeout-ms": 1200
        },
        "failover-errors": [
          "401",
          "403",
          "500",
          "502",
          "503",
          "504"
        ]
      },
      {
        "protocol": "https/1.1",
        "endpoints": [
          "failover.origin.example.com"
        ],
        "origin-host": "content.example.com" //Override Host Header
      }
    ]
  }
}

Origin Authentication

You can add authentication to your origin configuration by adding the acquisition-auth field to the MI.SourceMetadataExtended object. This allows you to securely authenticate requests to your origin server.

Header Authentication (MI.HeaderAuth)

Header authentication is used to pass an HTTP header and value to the origin when requesting content. The header name and value are agreed upon between the CDN and origin server.

To configure header authentication, add the acquisition-auth object to your origin configuration, setting the auth-type to "MI.HeaderAuth".

{
  "generic-metadata-type": "MI.SourceMetadataExtended",
  "generic-metadata-value": {
    "sources": [
      {
        "protocol": "https/1.1",
        "endpoints": [
          "origin.host.com"
        ],
        "acquisition-auth": {
          "auth-type": "MI.HeaderAuth",
          "auth-value": {
            "header-name": "X-Origin-Auth",
            "header-value": "YOUR_SECRET_KEY"
          }
        }
      }
    ]
  }
}

The CDN adds the specified header to every request sent to the origin server. The origin server should be configured to validate this header value to ensure the request is coming from an authorized CDN.

info

The header value should be a strong secret key that is known only to the CDN and origin server. This helps prevent unauthorized access to your origin content.

You can combine header authentication with other origin configuration options like failover and timeouts. Ensure the acquisition-auth block is included for each source definition (primary, failover) where authentication is required.

For example:

{
  "generic-metadata-type": "MI.SourceMetadataExtended",
  "generic-metadata-value": {
    "sources": [
      {
        "protocol": "https/1.1",
        "endpoints": [
          "primary-origin.example.com"
        ],
        "timeout-ms": 1200,
        "failover-errors": [
          "401",
          "403",
          "500",
          "502",
          "503",
          "504"
        ],
        "acquisition-auth": {
          "auth-type": "MI.HeaderAuth",
          "auth-value": {
            "header-name": "X-Origin-Auth",
            "header-value": "YOUR_SECRET_KEY"
          }
        }
      },
      {
        "protocol": "https/1.1",
        "endpoints": [
          "failover.origin.example.com"
        ],
        "timeout-ms": 1200,
        "acquisition-auth": {
          "auth-type": "MI.HeaderAuth",
          "auth-value": {
            "header-name": "X-Origin-Auth",
            "header-value": "YOUR_SECRET_KEY"
          }
        }
      }
    ]
  }
}

AWS Signature V4 Authentication (MI.AWSv4Auth)

This authentication method allows the CDN to sign requests to your origin using AWS Signature Version 4. This is commonly used when your origin is an AWS service like S3 that requires signed requests.

To configure AWS Signature V4 authentication, add the acquisition-auth object to your origin configuration, setting the auth-type to "MI.AWSv4Auth".

{
  "generic-metadata-type": "MI.SourceMetadataExtended",
  "generic-metadata-value": {
    "sources": [
      {
        "protocol": "https/1.1",
        "endpoints": [
          "my-bucket.s3.us-west-2.amazonaws.com"
        ],
        "origin-host": "my-bucket.s3.us-west-2.amazonaws.com", // Often required for S3
        "acquisition-auth": {
          "auth-type": "MI.AWSv4Auth",
          "auth-value": {
            "access-key-id": "<Your AWS Access Key ID e.g., \"AKIAX3YMABL...\">",
            "secret-access-key": {
              "secret-store-id": "<The keySetId attribute of the AWS access key uploaded to the Qwilt secure secret store, e.g., \"155\">"
            },
            "aws-region": "us-west-2",
            "aws-service": "s3",
            "host-name": "my-bucket.s3.us-west-2.amazonaws.com" // Should match the actual host being accessed
          }
        }
      }
    ]
  }
}

info

Storing the AWS Secret Access Key directly in the configuration is not supported. Use the Keys Manager API to upload the key to the Qwilt secure secret store. This action assigns a keySetId which you will use for reference.

Also note that the origin-host field within the source definition is required when using AWS Signature V4 for an S3 origin. It specifies the s3 bucket origin hostname.

You can combine AWS Signature V4 authentication with other origin configuration options like failover and timeouts within the MI.SourceMetadataExtended object. Ensure the acquisition-auth block is included for each source definition (primary, failover) where authentication is required.

For example:

{
  "generic-metadata-type": "MI.SourceMetadataExtended",
  "generic-metadata-value": {
    "sources": [
      {
        "protocol": "https/1.1",
        "endpoints": [
          "primary-origin.example.com"
        ],
        "timeout-ms": 1200,
        "failover-errors": [
          "401",
          "403",
          "500",
          "502",
          "503",
          "504"
        ],
        "acquisition-auth": {
          "auth-type": "MI.AWSv4Auth",
          "auth-value": {
            "access-key-id": "<Your AWS Access Key ID>",
            "secret-access-key": {
              "secret-store-id": "<The keySetId attribute of the AWS access key uploaded to the Qwilt secure secret store.>"
            },
            "aws-region": "us-west-2",
            "aws-service": "s3",
            "host-name": "my-bucket.s3.us-west-2.amazonaws.com"
          }
        }
      },
      {
        "protocol": "https/1.1",
        "endpoints": [
          "failover.origin.example.com"
        ],
        "timeout-ms": 1200,
        "acquisition-auth": {
          "auth-type": "MI.AWSv4Auth",
          "auth-value": {
            "access-key-id": "<Your AWS Access Key ID>",
            "secret-access-key": {
              "secret-store-id": "<The keySetId attribute of the AWS access key uploaded to the Qwilt secure secret store.>"
            },
            "aws-region": "us-west-2",
            "aws-service": "s3",
            "host-name": "my-bucket.s3.us-west-2.amazonaws.com"
          }
        }
      }
    ]
  }
}

Set an Origin Selection Rule by AWS Region

You can use the Origin Selection Rule to direct a request to an S3 origin, based on the location of the CDN cache that received the client request.

Each Qwilt CDN cache (also known as a Qwilt Node or Qwilt Box) is assigned a label that indicates the AWS region where it is located (e.g., use-east-1, us-east-2).

You can leverage this label to direct requests to an S3 origin in the same region as the Qwilt Cache that received the request.

To do this, create a match expression that uses the "cdnAwsRegion" variable, which represents the label value, and define what happens when there is a match.

In the following example, the expression var.cdnAwsRegion == 'us-east-2' sets an exact match condition for the label 'us-east-2'.

If the match condition is met, (i.e., if the receiving cache is labeled 'us-east-2'), the CDN will use the specified origin: example-bucket.s3.us-east-2.amazonaws.com.

{
  "generic-metadata-type": "MI.ProcessingStages",
  "generic-metadata-value": {
    "client-request": [
      {
        "stage-metadata": [
          {
            "generic-metadata": [
              {
                "generic-metadata-type": "MI.SourceMetadataExtended",
                "generic-metadata-value": {
                  "sources": [
                    {
                      "protocol": "https/1.1",
                      "endpoints": [
                        "example-bucket.s3.us-east-2.amazonaws.com"
                      ],
                      "acquisition-auth": {
                        "auth-type": "MI.AWSv4Auth",
                        "auth-value": {
                          "access-key-id": "AKIAIOSFODNN7EXAMPLE",
                          "secret-access-key": {
                            "secret-store-id": "60"
                          },
                          "aws-region": "us-east-2",
                          "aws-service": "s3",
                          "host-name": "example-bucket.s3.us-east-2.amazonaws.com"
                        }
                      }
                    }
                  ]
                }
              }
            ]
          }
        ],
        "match": {
          "expression": "var.cdnAwsRegion=='us-east-2'"
        }
      }
    ]
  }
}

You can also use a regex match when building the match condition. For example var.cdnAwsRegion ~= 'us-east' matches any label containing the string 'us-east', such as us-east-1 or us-east-2.

Valid cdnAwsRegion Values

af-south-1
ap-east-1
ap-northeast-1
ap-northeast-2
ap-northeast-3
ap-south-1
ap-southeast-2
ap-southeast-3
ap-southeast-4
ca-central-1
cn-north-1
cn-northwest-1
eu-central-1
eu-central-2
eu-north-1
eu-south-1
eu-south-2
eu-west-1
eu-west-2
eu-west-3
me-central-1
me-south-1
sa-east-1
us-east-1
us-east-2
us-gov-east-1
us-gov-west-1
us-west-1
us-west-2
GLOBAL

Supported Properties

The following properties are defined per source within the sources array. Not all properties are required or present for every source; each source includes only the properties relevant to its configuration.

Field	Description
protocol	The protocol to use when connecting to the origin (e.g., http/1.1, https/1.1).
endpoints	An array of origin server hostnames or IP addresses. For Single Origin, it will contain a single host. For Failover Origin, it will define the primary origin. For Round Robin origin, it will contain all the origin hosts.
origin-host (optional)	Use this field to override the host header value in requests to the origin. The field value is a string specifying the value to use for the Host HTTP header when connecting to the origin. If omitted, the CDN typically uses the hostname from the endpoints array. This is useful when the origin server relies on the Host header for virtual hosting or requires a specific value (e.g., for S3 bucket access). If the site uses the HTTPS protocol, both the header and SNI values are overridden.
connection-control (optional)	An object that allows managing the CDN to origin connection timeout and retry settings.
timeout-ms (optional)	Connection timeout to the origin in milliseconds.
failover errors (optional)	When configuring a failover origin, this attribute defines the HTTP status codes (as strings) that trigger a failover to the next source in the list.
acquisition-auth (optional)	This object defines the origin authentication settings.

Connection Control Attributes

The connection-control object supports the following fields:

Field	Description
connection-setup-timeout-ms	Timeout in milliseconds for establishing the initial TCP connection to the origin server.
byte-read-timeout-ms	Timeout in milliseconds for content acquisition from the origin after connection is established.
max-connection-retries-per-source	Number of times to retry if the initial connect or read attempt fails. If not explicitly defined, the retry default is zero.

Authentication Attributes

The acquisition-auth object supports the following fields:

Field	Description
auth-type	Sets the authentication method `MI.HeaderAuth` for header authentication, or `MI.AWSv4Auth` for AWS Signature V4 authentication.
auth-value	An object that specifies the authentication parameters.

Header Authentication

When the auth-type is MI.HeaderAuth, the auth-value field defines these values:

Field	Description
header-name	Specifies the name of the authentication header (e.g., X-Origin-Auth).
header-value	The secret value that will be sent in the header.

For example:

 "acquisition-auth": {
  "auth-type": "MI.HeaderAuth",
  "auth-value": {
    "header-name": "X-Origin-Auth",
    "header-value": "YOUR_SECRET_KEY"
  }
}

AWS Signature V4 Authentication

When the auth-type is MI.AWSv4Auth, the auth-value field defines these values:

Use the Keys Manager API to upload the key to the Qwilt secure secret store. This action assigns a key-id which you will use for reference.

Field	Description
access-key-id	The AWS Access Key ID associated with the AWS account or IAM user that has permissions to access the S3 bucket.
secret-access-key	This is an object that contains the secret-store-id field. The `secret-store-id` value is the `keySetId` attribute of the AWS access key you uploaded to the Qwilt secure secret store with the Keys Manager API.
aws-region	The AWS region where the service (e.g., S3 bucket) is hosted. For example, us-west-2.
aws-service	The AWS service being accessed (e.g., s3).
host-name	The hostname included in the signature calculation. Typically, this is the actual host endpoint, or the value provided in the `origin-host` field if it is defined.

For example:

"acquisition-auth": {
  "auth-type": "MI.AWSv4Auth",
  "auth-value": {
    "access-key-id": "AKIAIOSFODNN7EXAMPLE",
    "secret-access-key": {
      "secret-store-id": "60"
    },
    "aws-region": "us-west-2",
    "aws-service": "s3",
    "host-name": "my-bucket.s3.us-west-2.amazonaws.com"
  }
}

Overview​

Basic Examples​

Origin Authentication​

Header Authentication (MI.HeaderAuth)​

AWS Signature V4 Authentication (MI.AWSv4Auth)​

Set an Origin Selection Rule by AWS Region​

Supported Properties​

Connection Control Attributes​

Authentication Attributes​

Header Authentication​

AWS Signature V4 Authentication​

Overview

Basic Examples

Origin Authentication

Header Authentication (MI.HeaderAuth)

AWS Signature V4 Authentication (MI.AWSv4Auth)

Set an Origin Selection Rule by AWS Region

Supported Properties

Connection Control Attributes

Authentication Attributes

Header Authentication

AWS Signature V4 Authentication